Skip to main content

Interstitial

An interstitial ad is a fullscreen format, usually skippable after the first few seconds of its display. Because of this, it's commonly used in transitions of the app or game, such as completing a level or navigating to a different screen.

To start using interstitial ads, just call load() (or Load()/present()/Show() depending on platform) using a valid placement id and then use one of the available present/show functions when you need it to be displayed.

Start loading an ad​

import XMediator

XMediatorAds.startWith(appKey: "<your-app-key>") { result in
    XMediatorAds.interstitial.load(placementId: "<placement-id>")
}

Presenting an ad​

Calling isReady() will return if there's an interstitial available to be shown, regardless of its placement id. If multiple ads with different placement ids were previously loaded, the SDK will try to show the best one available.

if XMediatorAds.interstitial.isReady() {
    XMediatorAds.interstitial.present(fromViewController: self, fromAdSpace: "interstitial-ad-space")
}

Presenting an ad with placementId​

When the app needs to present an ad for a specific placement id, isReady(withPlacementId:) and present(withPlacementId:) can be alternatively used.

if XMediatorAds.interstitial.isReady(withPlacementId: "<placement-id>") {
    XMediatorAds.interstitial.present(withPlacementId: "<placement-id>", fromViewController: self, fromAdSpace: "interstitial-ad-space")
}

Built-in features​

Auto loading​

Dismissed or failed to show ads will automatically trigger a new load request.

Auto retry​

Failed to load ads will make a retry attempts, with an exponential backoff.

Additional settings​

Register ad callbacks​

Every ad callback indicates the placement id of the interstitial ad that triggered the event.

// Assign a delegate to handle the ad callbacks
XMediatorAds.interstitial.addDelegate(self)

// [...]

func didLoad(placementId: String, result: LoadResult) {
    print("Interstitial loaded! placementId: \(placementId)")
}

func didPresent(placementId: String) {
    print("Interstitial is being presented! placementId: \(placementId)")
}

func failedToPresent(placementId: String, error: PresentError) {
    // If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
    print("Interstitial failed to present. placementId: \(placementId), Reason: \(error.localizedDescription)")
}

func didRecordImpression(placementId: String, data: ImpressionData) {
    print("Interstitial impression, with revenue: \(data.revenue). placementId: \(placementId)")
}

func willDismiss(placementId: String) {
    print("Interstitial will be dismissed! placementId: \(placementId)")
}

func didDismiss(placementId: String) {
    // If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
    print("Interstitial dismissed! placementId: \(placementId)")
}

func didClick(placementId: String) {
    print("Interstitial clicked! placementId: \(placementId)")
}

Code example​

In addition to the example below, you can see a real implementation in our iOS Demo App.

InterstitialViewController.swift
import UIKit
import XMediator

class InterstitialViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    @IBAction func startButtonTouchUpInside(_ sender: Any) {
        XMediatorAds.startWith(appKey: "<your-app-key>") { result in
            XMediatorAds.interstitial.addDelegate(self)

            // Start loading an interstitial. Subsequent loads or retries are handled by the sdk
            XMediatorAds.interstitial.load(placementId: "<placement-id>")
        }
    }

    @IBAction func presentButtonTouchUpInside(_ sender: Any) {
        if XMediatorAds.interstitial.isReady() {
            XMediatorAds.interstitial.present(fromViewController: self)
        }
    }
}

extension InterstitialViewController: InterstitialAdsDelegate {
    func didLoad(placementId: String, result: LoadResult) {
        print("Interstitial loaded! placementId: \(placementId)")
    }

    func didPresent(placementId: String) {
        print("Interstitial is being presented! placementId: \(placementId)")
    }

    func failedToPresent(placementId: String, error: PresentError) {
        // If you need to resume your app's flow, make sure to do it here and in the didDismiss callback
        print("Interstitial failed to present. placementId: \(placementId), Reason: \(error.localizedDescription)")
    }

    func didRecordImpression(placementId: String, data: ImpressionData) {
        print("Interstitial impression, with revenue: \(data.revenue). placementId: \(placementId)")
    }

    func willDismiss(placementId: String) {
        print("Interstitial will be dismissed! placementId: \(placementId)")
    }

    func didDismiss(placementId: String) {
        // If you need to resume your app's flow, make sure to do it here and in the failedToPresent callback
        print("Interstitial dismissed! placementId: \(placementId)")
    }

    func didClick(placementId: String) {
        print("Interstitial clicked! placementId: \(placementId)")
    }
}